#Copyright (c) 2012-8 Civa Lin. All rights reserved.
"""
Routine Utility 函式工具模組

本模組提供函式與流水線的撰寫支援，是官方 functools 的補充。
"""

import functools

def coroutine(func):
    '''透過使用此一裝飾器，可簡單將 generator function
    轉換為 coroutine。

        提示：
            coroutine 外部，可以用 coroutine.send(input_data) 將資料打入
            coroutine 外部，可以用 coroutine.close() 將其關閉。
            coroutine 內部，輸入資料將會從 (yield) 關鍵字處接收
            coroutine 內部若要回傳，可參考以下形式來回傳：
                while True:
                    input_data = (yield return_data)
                    # 處理 input_data、產生 return_data 直到迴圈底部...
    '''
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        generator = func(*args, **kwargs)
        next(generator)
        return generator
    return wrapper

